What the gap is

RequestOptions.timeout is a documented contract on the public env.send / ctx.mcpReq.send surface (packages/core/src/shared/context.ts:78-82): "If exceeded, an SdkError with code RequestTimeout will be raised… If not specified, DEFAULT_REQUEST_TIMEOUT_MSEC will be used." The dispatcher's ctx.mcpReq.send wrapper does not apply the timeout itself — it forwards options straight through to the env.send sink, which is responsible for honoring it.

The two sinks diverge:

• BackchannelCompat.makeEnvSend (backchannelCompat.ts:79-83) reads opts?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC and arms a setTimeout that rejects with SdkError(SdkErrorCode.RequestTimeout, …).
• ContinuationCompat._suspendingSend (this PR, lines ~391-435) reads only opts?.signal (lines 392-394, 415-419, 422, 430). opts?.timeout, opts?.resetTimeoutOnProgress, and opts?.maxTotalTimeout are never referenced.

Step-by-step

1. A handler calls await ctx.mcpReq.send({method: 'elicitation/create', …}, {timeout: 5000}).
2. Dispatcher forwards to env.send(req, {timeout: 5000, signal: …}).
3. Backchannel path: makeEnvSend arms setTimeout(…, 5000); if the client doesn't POST a response within 5s, the promise rejects with RequestTimeout and the handler's catch runs.
4. Continuation path: _suspendingSend queues the request into the current batch, flushes an incomplete ask on the next microtask, and the returned promise settles only when (a) cont.nextAnswer() resolves on resume, (b) opts.signal aborts, or (c) the frame-level TTL fires via _arm → cont.fail(reason). With default ttlMs = 300_000, the handler waits up to 5 minutes instead of the requested 5 seconds.

Why nothing else covers it

The continuation-level TTL (_arm) is a frame-wide bound, not a per-send bound, and defaults to 60× the value the handler asked for. The opts.signal plumbing handles cancellation but not timeout. And because both the class JSDoc and the ShttpHandlerOptions.continuations doc say this path "takes precedence" / "wins when both are set", the PR is explicitly positioning ContinuationCompat as a drop-in for BackchannelCompat — so the same handler source silently changes semantics depending on which option the operator configured.

Impact and severity

This is a parity/contract-clarity gap, not a correctness break: nothing hangs forever (TTL bounds it), and the protocol flow is correct. There's also a defensible argument that honoring DEFAULT_REQUEST_TIMEOUT_MSEC (60s) on a human-in-the-loop suspend path would be wrong — the whole point of Option H is that the client may take human-scale time to answer. Hence nit.

Suggested fix

Minimal: add a sentence to the _suspendingSend JSDoc (and/or the class JSDoc) stating that RequestOptions.{timeout, resetTimeoutOnProgress, maxTotalTimeout} are not applied on this path and the frame-level ttlMs governs instead.

Alternatively, if you want strict parity for explicit timeouts only: when opts?.timeout !== undefined, arm a local setTimeout(() => reject(new SdkError(SdkErrorCode.RequestTimeout, …)), opts.timeout) alongside the existing signal listener and clear it in both settle.then branches. (Skipping the ?? DEFAULT_REQUEST_TIMEOUT_MSEC fallback avoids the 60s default firing on every elicitation.)

What the bug is

In _drive's fresh-request branch (incomingState === undefined), the per-principal counter is incremented, a requestState token is generated, a FrameEntry is inserted into _frames, and a TTL timer is armed — all before _startRunner kicks off the handler and before any env.send has been called. The slot is released only when the drain loop later sees 'done' or 'runnerError' and calls _delete(token). So every request routed through continuations.wrap(...) consumes one global slot and one per-principal slot for its entire in-flight duration, whether or not it ever suspends.

There is no leak: the done branch cleans up correctly, so steady-state size returns to 0 after a non-suspending handler finishes (the "handler that never calls env.send passes through unchanged" test confirms this). The issue is the transient occupancy and the doc/behavior mismatch.

Code path

shttpHandler wraps cb.onrequest unconditionally with continuations.wrap(...) whenever continuations is configured — there is no per-method opt-out, so ping, tools/list, prompts/list, and fast non-elicitating tools/call all flow through _drive. Inside _drive:

1. incomingState === undefined → fresh-request branch.
2. _resolvePrincipal(env) resolves owner.
3. _perPrincipalCount.set(owner, n + 1) — quota consumed.
4. token = this._generate() — UUID minted.
5. _frames.set(token, { cont, timer: this._arm(token), owner, draining: true }) — global slot consumed, TTL timer armed.
6. _startRunner(...) begins iterating the real handler.
7. Handler yields a result and returns; runner pushes {kind: 'message'} then {kind: 'done'}.
8. Drain loop sees done, calls _delete(token) → slot released.

Between steps 3–5 and step 8, the request holds a slot even though no frame is parked.

Why existing code doesn't prevent it

The capacity checks (_frames.size >= this._max, n >= this._perPrincipalMax) and the JSDoc all describe suspended frames — i.e., handlers parked at an await env.send(...). But because registration happens before the runner starts, the checks actually gate in-flight concurrency, not suspension count. Nothing in _drive distinguishes "will suspend" from "will complete synchronously"; that's only knowable once the first 'incomplete' ask appears on the channel.

Concrete walkthrough

With defaults (maxContinuations=1000, perPrincipalMax=ceil(1000/10)=100), suppose principal alice fires 101 concurrent tools/call requests for a tool that does I/O for 200ms but never calls env.send:

• Requests 1–100 each enter the fresh branch, increment _perPrincipalCount['alice'] to 100, and start their runners.
• Request 101 enters the fresh branch, finds n === 100 >= perPrincipalMax, and throws "principal at per-principal capacity" → shttpHandler catches it and returns a 500.
• A few hundred ms later all 100 runners push done, slots drain to 0 — but request 101 already failed.

Zero frames were ever actually parked. An operator who read the JSDoc ("Maximum suspended frames a single principal may hold") and set perPrincipalMax: 3 to bound pending elicitations would be surprised to find it rejecting the 4th concurrent non-elicitating request. There's also avoidable per-request overhead (crypto.randomUUID(), setTimeout, AbortController, two Channel allocations) for handlers that never suspend.

Impact and severity

This is a design/doc-accuracy issue rather than a correctness bug. The eager accounting is defensible as a more conservative DoS guard — in-flight coroutines also consume memory, and the runner's error path relies on this._frames.has(token) — and at default caps (1000/100) it's unlikely to bite in practice. But the three JSDoc strings (maxContinuations, perPrincipalMax, get size()) explicitly say "suspended", which the implementation does not honor. Filing as nit: worth fixing before merge but not blocking.

How to fix

Two options:

(a) Lazy registration — in the fresh branch, create the Continuation and start the runner, but don't increment _perPrincipalCount, generate a token, insert into _frames, or arm the TTL timer until the drain loop pulls the first 'incomplete' ask. If the runner reaches done/runnerError without ever producing incomplete, no slot was ever consumed. This also makes _resolvePrincipal's "refusing to suspend without a principal" error fire only when a suspend actually happens. Note the runner's if (this._frames.has(token)) guard would need adjusting (e.g., track liveness on the Continuation instead).

(b) Doc fix — keep the eager accounting and reword the JSDoc on maxContinuations, perPrincipalMax, and size from "suspended frames" to "in-flight or suspended frames routed through this store", so operators set caps with the right mental model.

Option (a) is the cleaner fix and also addresses the related concern that anonymous/principal resolution fires for requests that never suspend; option (b) is the minimal change if the conservative gating is intentional.

What the bug is

The detailed JSDoc that documents ContinuationCompat's purpose, security model, single-process constraint, and mutual exclusivity with BackchannelCompat is orphaned — it is not associated with the export class ContinuationCompat declaration it describes. TypeScript and TSDoc tooling only attach the immediately preceding doc comment to a declaration, and here two intervening declarations break that adjacency.

The specific code path

In packages/server/src/server/continuationCompat.ts:

/**
 * Opt-in suspend/resume continuation store for shttpHandler...
 *   ...security model, single-process caveat, BackchannelCompat exclusivity...
 */                                            // ← lines 124-146, intended class doc
/**
 * Validated identity to bind a frame to...
 */
function principalOf(env: RequestEnv): ... {  // ← line ~151, consumes the second /** */
    ...
}

interface FrameEntry { ... }                   // ← lines ~155-167

export class ContinuationCompat {             // ← line ~169, no preceding /** */
    ...
}

The second /** */ block immediately follows the first, so the first block becomes a free-floating leading comment on principalOf (effectively dead in emit). FrameEntry then sits between principalOf and the class. By the time the compiler reaches export class ContinuationCompat, there is no doc comment directly above it.

Why existing code doesn't prevent it

Nothing in the build catches this: the file compiles fine, lint rules don't flag stacked JSDoc blocks, and tests cover runtime behaviour only. The PR adds export { ContinuationCompat } to packages/server/src/index.ts, so the symbol is part of the package's public surface, but .d.ts emission will produce export declare class ContinuationCompat { ... } with no leading comment.

Step-by-step proof

1. tsc --declaration walks declarations and copies the immediately adjacent leading JSDoc into the .d.ts for each exported symbol.
2. For principalOf, the immediately adjacent JSDoc is the small "Validated identity..." block — that gets attached (but principalOf is module-private, so it never reaches .d.ts anyway).
3. The large "Opt-in suspend/resume..." block is not immediately adjacent to any declaration (another /** */ follows it), so it is treated as an orphan and dropped from emit.
4. interface FrameEntry has no JSDoc above it (the preceding token is } closing principalOf).
5. export class ContinuationCompat has no JSDoc above it (the preceding token is } closing FrameEntry).
6. Result: hovering ContinuationCompat in an IDE, or reading the published .d.ts, shows no documentation. The carefully-written tenant-isolation rules, the "single-process only" warning, and the allowAnonymousSuspend security note are invisible to consumers.

Impact

Documentation-only — no runtime effect. But the PR description itself flags this as "the most security-sensitive new code in the stack", and the lost prose is exactly the part that tells deployers (a) frames are in-memory and need sticky routing, (b) anonymous suspend is unsafe, and (c) configuring this alongside BackchannelCompat has a defined precedence. Hiding that from API docs/IDE tooling undermines the point of writing it.

How to fix

Either move function principalOf and interface FrameEntry above the large JSDoc block, or relocate that JSDoc so it sits directly on top of export class ContinuationCompat. The latter is the smaller diff:

function principalOf(...) { ... }
interface FrameEntry { ... }

/**
 * Opt-in suspend/resume continuation store for shttpHandler...
 */
export class ContinuationCompat { ... }

What the bug is

Commit da01f10 ("yield JSON-RPC error (not throw) for principal/capacity guards so SSE clients receive it") fixed the runtime issue from review comment #3226706458 by replacing the three fresh-request throw statements in _drive with yield this._capacityError(request.id, ...) + return. The maxContinuations JSDoc was correctly updated in that commit to read:

New suspensions beyond this cap yield a JSON-RPC -32000 error response for the request.

But the two sibling option docs in the same ContinuationCompatOptions interface were missed:

• allowAnonymousSuspend (lines 45-49): "If false (default), {@linkcode ContinuationCompat.drive} throws when no principal can be derived..."
• perPrincipalMax (lines 51-54): "Maximum suspended frames a single principal may hold. New suspensions beyond this throw."

Both now describe behavior the code no longer ships. There's also a dangling {@linkcode ContinuationCompat.drive} reference — drive is not a public method (the implementation is private _drive, and consumers only ever see the wrapped onrequest returned from wrap()), so the linkcode resolves to nothing in TSDoc tooling.

Why existing code doesn't prevent it

This is a partial migration: da01f10 touched all three runtime guards but only one of the three corresponding doc strings. Nothing in the build flags doc/code drift, and the tests (which were also updated in da01f10 to assert error: { code: -32_000 } at status: 200) only exercise runtime behavior. The internal inconsistency — one option says "yield a JSON-RPC -32000 error", the next two say "throw" — makes it clearly an oversight in the fixup rather than an intentional distinction.

Step-by-step proof

1. packages/server/src/index.ts exports ContinuationCompatOptions as public API, so its JSDoc is emitted into .d.ts and surfaces in IDE hovers.
2. Read allowAnonymousSuspend doc → it promises a throw when no principal is derivable.
3. Trace the implementation: _drive fresh-request branch → owner === undefined && !this._allowAnonymous → yield this._capacityError(request.id, 'ContinuationCompat: refusing to suspend without a principal ...'); return;. No throw.
4. Confirm via the test "refuses to suspend without a principal by default": it asserts r.status === 200 and error: { code: -32_000 } — i.e., a yielded JSON-RPC error, not a thrown 500.
5. Same for perPrincipalMax: doc says "throw"; code at n >= this._perPrincipalMax does yield this._capacityError(...); test "rejects new suspension when principal is at perPrincipalMax" asserts status: 200 + error: { code: -32_000 }.
6. Compare with maxContinuations doc on line 30, which was updated to "yield a JSON-RPC -32000 error response" — proving the intent and that the other two were simply missed.

Impact

Documentation-only — no runtime effect. But ContinuationCompatOptions is part of the package's public surface, so the "throws" claim reaches consumers via .d.ts and IDE hovers. An operator reading the doc would expect allowAnonymousSuspend: false to surface as a thrown error / 500 (and might wire onerror or HTTP-level error handling accordingly), when in practice the client receives a 200 with a JSON-RPC -32000 body. The {@linkcode ContinuationCompat.drive} reference also points at a nonexistent public symbol and will render as a dead link in TSDoc output.

How to fix

Reword both to match maxContinuations:

/**
 * If `false` (default), requests with no derivable principal (no `authInfo.token`
 * and no `mcp-session-id`) yield a JSON-RPC `-32000` error response. Anonymous
 * suspension means any caller can resume any frame; only enable this for trusted
 * single-tenant deployments.
 */
allowAnonymousSuspend?: boolean;
/**
 * Maximum suspended frames a single principal may hold. New suspensions beyond this
 * yield a JSON-RPC `-32000` error response. Prevents one tenant exhausting
 * `maxContinuations`. Defaults to `Math.ceil(maxContinuations / 10)`.
 */
perPrincipalMax?: number;

Filing as a nit since it's prose-only with no runtime impact, but it should land in the same PR — the stale text was introduced by this PR's own fixup commit, and the three options now contradict each other in the public type definition.

What the gap is

handleHttp is the public entry point (shttpHandler is @internal per its own JSDoc), and HandleHttpOptions is a straight re-export of ShttpHandlerOptions (handleHttp.ts:54), so options.continuations added in this PR is now part of handleHttp's public surface. The function-level JSDoc on handleHttp (handleHttp.ts:19-40) explicitly enumerates the compat helpers in prose:

Supply a SessionCompat via options.session to serve clients that send Mcp-Session-Id …, and a BackchannelCompat via options.backchannel to let handlers' ctx.mcpReq.send (e.g. elicitInput, requestSampling) reach those clients over the open POST SSE stream.

It does not mention options.continuations / ContinuationCompat, which this PR adds as the third compat helper and the alternative path for exactly the same ctx.mcpReq.send capability.

Why this is worth fixing despite the doc not being exhaustive

It's true that handleHttp's JSDoc is a usage overview rather than an option reference — it already omits enableJsonResponse, eventStore, retryInterval, supportedProtocolVersions, and onerror, and the per-option documentation lives on ShttpHandlerOptions where IDE hover picks it up. So the omission of continuations is not hiding the option from consumers.

But the omitted options are orthogonal infrastructure knobs. backchannel and continuations are different: they are siblings for the same feature (both supply env.send so ctx.mcpReq.send resolves), they are mutually exclusive (the option JSDoc here says "When both this and backchannel are set, this takes precedence"), and the handleHttp prose specifically singles out backchannel as the way to make ctx.mcpReq.send work. After this PR that sentence is no longer the whole story — a reader of the public entry point would reasonably conclude backchannel is the only option, when in fact the SEP-2322 path is the forward-looking one.

The PR is internally inconsistent on this: ContinuationCompat's own class JSDoc says it is "for {@linkcode handleHttp}" and wrap()'s JSDoc says "Called by {@linkcode handleHttp} when this instance is configured", and the prior stack PRs each added their compat helper (session, backchannel) to exactly this paragraph. This one should follow suit.

Step-by-step

1. packages/server/src/index.ts exports handleHttp and ContinuationCompat as public API; shttpHandler is not exported (it's @internal).
2. A consumer reads handleHttp's JSDoc to learn how to enable elicitInput/requestSampling in handlers. Lines 37-39 say: pass options.backchannel.
3. Nothing in that prose hints that options.continuations exists or that it is the SEP-2322 alternative for stateless deployments — even though ShttpHandlerOptions.continuations (this hunk, lines 68-75) and the ContinuationCompat class doc both describe it as the handleHttp integration and document the precedence over backchannel.
4. The consumer would have to discover continuations by expanding HandleHttpOptions in their IDE, rather than from the canonical entry-point prose that already lists its sibling.

Impact

Documentation-only; no runtime effect. The option is fully documented at the type level, so this is purely an asymmetry in the function-level prose. Filing as nit.

Suggested fix

Append one clause to handleHttp.ts:37-39, e.g.:

 * and a `BackchannelCompat` via `options.backchannel` to let handlers'
 * `ctx.mcpReq.send` (e.g. `elicitInput`, `requestSampling`) reach those
 * clients over the open POST SSE stream — or a `ContinuationCompat` via
 * `options.continuations` for the SEP-2322 suspend/resume path on stateless
 * transports (takes precedence over `backchannel` when both are set).

(Note: the edit is in handleHttp.ts, which this PR doesn't touch; the comment is anchored on the ShttpHandlerOptions.continuations hunk since that's where the option enters the diff.)

What the gap is

Commit bd3442e introduced the per-round abort bridge in _drive (continuationCompat.ts:323-334 plus the removeEventListener in the finally at line 371) so that notifications/cancelled or an SSE disconnect on a resume round actually reaches the long-lived runner via cont.abort. This was the fix for the 🔴 review comment #3228252344, where round-2's env.signal was previously never observed and a resumed handler ran until ttlMs with no way to cancel it.

continuationCompat.test.ts does not exercise this path. Reading the file end-to-end, the eleven tests cover: round-trip suspend/resume, SSE-mode notifications, batched concurrent env.send, principal-mismatch reject, unknown requestState, missing inputResponses slot, concurrent-resume guard, TTL eviction, anonymous-suspend reject, perPrincipalMax, and the non-suspending pass-through. A grep of the file for cancelled, abort, signal, or cancel (case-insensitive) returns zero matches — none of the tests POST a notifications/cancelled, abort an AbortController, or close an SSE stream mid-drain.

Why this matters

The bridge is exactly the kind of async/lifecycle code that regresses silently:

• It pairs addEventListener('abort', onAbort, { once: true }) with a removeEventListener in a finally, so a refactor that returns early (or moves the finally) could leave the listener attached and kill a parked frame on a late abort — the very behavior the comment at line 327 says it must avoid.
• It has an already-aborted fast path (if (env.signal?.aborted) cont.abort.abort(...)) that is easy to drop in a future cleanup.
• It is the only link between shttpHandler's per-request ctrl.signal and the frame-lifetime cont.abort.signal; removing it reverts to the pre-bd3442e behavior with no test failing.

REVIEW.md's checklist explicitly requires "New behavior has vitest coverage including error paths", and the PR description self-identifies this file as "the most security-sensitive new code in the stack". Shipping the most recent fixup commit with zero regression protection means a future refactor could silently re-break resume-round cancellation.

Step-by-step proof of the gap

1. git show bd3442e -- packages/server/src/server/continuationCompat.ts adds the onAbort listener block (lines 323-334) and the env.signal?.removeEventListener('abort', onAbort) in the drain-loop finally (line 371), and rewrites _startRunner to pass only cont.abort.signal (line 387).
2. git show bd3442e -- packages/server/test/server/continuationCompat.test.ts shows no hunk — the commit touched only the source file.
3. rg -in 'cancelled|abort|signal|cancel' packages/server/test/server/continuationCompat.test.ts → no output.
4. Therefore, deleting lines 323-334 and 371 (reverting to the pre-fix state where the resume round's env.signal is never read) would leave pnpm vitest run continuationCompat green. The original bug — notifications/cancelled for a resume id being silently dropped — could reappear with no failing test.

Suggested test

Something along these lines would lock the fix in:

it('notifications/cancelled on a resume round aborts the frame', async () => {
    continuations = new ContinuationCompat({ allowAnonymousSuspend: true });
    let release!: () => void;
    const gate = new Promise<void>(r => (release = r));
    const cb: ShttpCallbacks = {
        async *onrequest(req, env) {
            await env!.send!({ method: 'elicitation/create' });
            await gate;                       // long post-resume work
            yield { jsonrpc: '2.0', id: req.id, result: { ok: true } };
        }
    };
    const handler = shttpHandler(cb, { continuations, enableJsonResponse: true });

    const r1 = await handler(post({ jsonrpc: '2.0', id: 1, method: 'x' }));
    const inc = asIncomplete((await r1.json()) as JSONRPCMessage);

    const resumeP = handler(post({
        jsonrpc: '2.0', id: 2, method: 'x',
        params: { requestState: inc.requestState, inputResponses: { r0: {} } }
    }));
    await Promise.resolve();                  // let the resume drain start

    await handler(post({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { requestId: 2 } }));

    const m2 = (await (await resumeP).json()) as JSONRPCMessage;
    expect(m2).toMatchObject({ id: 2, error: { code: -32603 } });
    expect(continuations.size).toBe(0);
    release();
});

A second variant that asserts the listener is detached (suspend, return on incomplete, then abort the round-1 controller and verify continuations.size === 1 — frame still parked) would cover the finally half.

Severity

Nit — this is a coverage gap, not a runtime defect; the bridge itself is correct. But it is a fair ask given the bridge was a bugfix in code the PR flags as security-sensitive, and the repo's own review checklist requires error-path coverage.